home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / CD32 / CD32_Support / examples / cdgsxl / doc / RunCDXL.doc < prev   
Encoding:
Text File  |  1993-04-08  |  13.7 KB  |  672 lines
  1. TABLE OF CONTENTS
  2.  
  3. RunCDXL/Boxit
  4. RunCDXL/CDConfig
  5. RunCDXL/CDDeviceInit
  6. RunCDXL/CDDeviceTerm
  7. RunCDXL/CDXLCallBack
  8. RunCDXL/CDXLFreeOb
  9. RunCDXL/CDXLObtain
  10. RunCDXL/CDXLTerm
  11. RunCDXL/FreeXList
  12. RunCDXL/GetCDInfo
  13. RunCDXL/NewCDTV_XL
  14. RunCDXL/NewCD_XL
  15. RunCDXL/Pan2Display
  16. RunCDXL/PlayCDXL
  17. RunCDXL/RunCDXL
  18. RunCDXL/SendIOR
  19. RunCDXL/StartCDXL
  20.  
  21. RunCDXL/Boxit                                                      RunCDXL/Boxit
  22.  
  23.    NAME
  24.     Boxit -- Draw a box in color 0 around the CDXL image.
  25.  
  26.    SYNOPSIS
  27.     Boxit( disp_def, CDXL_ob );
  28.  
  29.     VOID Boxit( DISP_DEF * , CDXLOB * );
  30.  
  31.  
  32.    FUNCTION
  33.     Draw a box in color 0 around the CDXL image. This may be necessary
  34.     to avoid some HAMing problems.
  35.  
  36.  
  37.    INPUTS
  38.     disp_def = pointer to DISP_DEF which describes the display.
  39.     CDXL_ob = pointer to the CDXLOB to draw box around.
  40.  
  41.    RESULTS
  42.     A box is draw in color 0 around the CDXL image.
  43.  
  44.    NOTES
  45.  
  46.  
  47.    SEE ALSO
  48.     runcdxl.h cdxlob.h
  49.  
  50.    BUGS
  51.     None?
  52.  
  53. RunCDXL/CDConfig                                                RunCDXL/CDConfig
  54.  
  55.    NAME
  56.     CDConfig -- Send a CD_CONFIG command to cd.device.
  57.  
  58.    SYNOPSIS
  59.     success = CDConfig( tag, ... );
  60.  
  61.     BOOL CDConfig( ULONG tag, ... );
  62.  
  63.    FUNCTION
  64.     Send a CD_CONFIG command to cd.device. 
  65.  
  66.  
  67.    INPUTS
  68.     tag = taglist of CD_CONFIG commands.
  69.  
  70.    EXAMPLE
  71.     success = CDConfig(TAGCD_READXLSPEED, 150,// Set READXLSPEED
  72.                TAGCD_XLECC, FALSE,    // Turn off error correction
  73.                TAG_END );
  74.  
  75.    RESULTS
  76.     If successful cd.device will be configured to the 
  77.     taglist specifications.
  78.  
  79.    NOTES
  80.  
  81.  
  82.    SEE ALSO
  83.  
  84.    BUGS
  85.     None?
  86.  
  87. RunCDXL/CDDeviceInit                                        RunCDXL/CDDeviceInit
  88.  
  89.    NAME
  90.     CDDeviceInit -- Open cd/cdtv.device.
  91.  
  92.    SYNOPSIS
  93.     success = CDDeviceInit( opened, CDXL_ob );
  94.  
  95.     BOOL CDDeviceInit( ULONG * , CDXLOB * );
  96.  
  97.    FUNCTION
  98.     Attempts to open cd/cdtv.device if not already opened.
  99.     Tries to open cd.device first, if not successful, tries
  100.     for cdtv.device. Will set CDXL_ob->flags bit CDTV_DEVICE
  101.     to reflect if cdtv.device was opened as opposed to cd.device.
  102.  
  103.    INPUTS
  104.     opened = pointer to a ULONG which if NON NULL will be set to
  105.         TRUE if device was opened by this call.
  106.  
  107.     CDXL_ob = pointer to defining CDXLOB control structure.
  108.  
  109.    RESULTS
  110.     If device is succesfully opened, will returen TRUE. The opened
  111.     paramater will be set to TRUE if this call opened the device or
  112.     to FALSE if the device was opened by a prior call. CDXL_ob->flags
  113.     will have the CDTV_DEVICE bit set if cdtv.device was opened as
  114.     opposed to cd.device.
  115.  
  116.    NOTES
  117.  
  118.  
  119.    SEE ALSO
  120.     cdxlob.h
  121.  
  122.    BUGS
  123.     None?
  124.  
  125. RunCDXL/CDDeviceTerm                                       RunCDXL/CDDeviceTerm
  126.  
  127.    NAME
  128.     CDDeviceTerm -- Close cd/cdtv.device.
  129.  
  130.    SYNOPSIS
  131.     CDDeviceTerm( CDXL_ob );
  132.  
  133.     VOID CDDeviceTerm( CDXLOB * );
  134.  
  135.    FUNCTION
  136.     Close cd/cdtv.device, depending upon which one was opened.
  137.  
  138.  
  139.    INPUTS
  140.     CDXL_ob = pointer to defining CDXLOB control structure.
  141.  
  142.  
  143.    RESULTS
  144.     Everything opened/allocated by CDDeviceInit wilil be
  145.     closed/freed.
  146.  
  147.    NOTES
  148.  
  149.  
  150.    SEE ALSO
  151.     cdxlob.h
  152.  
  153.    BUGS
  154.     None?
  155.  
  156. RunCDXL/CDXLCallBack                                       RunCDXL/CDXLCallBack
  157.  
  158.    NAME
  159.     CDXLCallBack -- CDXL callback function.
  160.  
  161.    SYNOPSIS
  162.     __interrupt __asm __saveds
  163.     CDXLCallBack( register __a1 APTR, register __a2 struct CDXL *);
  164.  
  165.     xl->IntCode = (VOID(* )())CDXLCallBack;
  166.  
  167.    FUNCTION
  168.     This function is called as an interrupt whenever a transfer
  169.     node has been completed. It increments the counter, flips
  170.     the curVideo variable and signals the main task.
  171.  
  172.    INPUTS
  173.  
  174.  
  175.    RESULTS
  176.  
  177.  
  178.    NOTES
  179.  
  180.  
  181.    SEE ALSO
  182.  
  183.    BUGS
  184.     None?
  185.  
  186. RunCDXL/CDXLFreeOb                                          RunCDXL/CDXLFreeOb
  187.  
  188.    NAME
  189.     CDXLFreeOb -- Free the CDXLOB control structure and its buffers.
  190.  
  191.    SYNOPSIS
  192.     CDXLFreeOb( cdxl_OB );
  193.  
  194.     VOID CDXLFreeOb( CDXLOB * );
  195.  
  196.    FUNCTION
  197.     Free the CDXLOB control structure and its buffers. Safe to call
  198.     if cdxl_OB is NULL or if any of its buffers are NULL.
  199.  
  200.    INPUTS
  201.     cdxl_OB = pointer to defining CDXLOB control structure.
  202.  
  203.  
  204.    RESULTS
  205.     All memory allocated for the CDXLOB control structure
  206.     will be freed.
  207.  
  208.    NOTES
  209.  
  210.  
  211.    SEE ALSO
  212.     cdxlob.h
  213.  
  214.    BUGS
  215.     None?
  216.  
  217. RunCDXL/CDXLObtain                                         RunCDXL/CDXLObtain
  218.  
  219.    NAME
  220.     CDXLObtain -- Allocate a CDXLOB control structure 
  221.     and its buffers and do setup.
  222.  
  223.    SYNOPSIS
  224.     error = CDXLObtain( CDXLFile, disp_def, CDXLob, flags, inti );
  225.  
  226.     int CDXLObtain( UBYTE *, DISP_DEF *, CDXLOB **, ULONG, struct TagItem *);
  227.  
  228.    FUNCTION
  229.     Allocate a CDXLOB control structure, setup the structure 
  230.     as defined by the first PAN found in the CDXL file. Set
  231.     up the disp_def structure as defined by the first PAN structure
  232.     found in the file.
  233.  
  234.    INPUTS
  235.     CDXLFile = pointer to UBYTE path to CDXLFile.
  236.     disp_def = pointer to DISP_DEF, display definition structure.
  237.     CDXLob = pointer to a CDXLOB pointer. If this call is successful,
  238.         this pointer will point to the allocated CDXLOB control
  239.         structure.
  240.     flags = ULONG flags.
  241.     inti = a taglist with possible XLTAG_Left, XLTAG_Top, and 
  242.         XLTAG_Volume entries.
  243.  
  244.    RESULTS
  245.     0 if successful. An error code if not. Errors defined in
  246.     runcdxl.h
  247.  
  248.  
  249.    NOTES
  250.  
  251.  
  252.    SEE ALSO
  253.     runcdxl.h cdxlob.h
  254.  
  255.    BUGS
  256.     None?
  257.  
  258. RunCDXL/CDXLTerm                                           RunCDXL/CDXLTerm
  259.  
  260.    NAME
  261.     CDXLTerm -- Shut down everything CDXL related.
  262.  
  263.    SYNOPSIS
  264.     CDXLTerm( CDXL_ob );
  265.  
  266.     VOID CDXLTerm( CDXLOB * );
  267.  
  268.    FUNCTION
  269.     CDXL shutdown function. Terminates the audio, Does an 
  270.     AbortIO/WaitIO and a CD_SEEK to force the drive to stop.
  271.     Closes the device and frees its resources, frees the
  272.     transfer list and the CDXLOB and and signals allocated.
  273.  
  274.    INPUTS
  275.     CDXL_ob = pointer to defining CDXLOB control structure.
  276.  
  277.  
  278.    RESULTS
  279.  
  280.  
  281.    NOTES
  282.  
  283.  
  284.    SEE ALSO
  285.     cdxlob.h
  286.  
  287.    BUGS
  288.     None?
  289.  
  290. RunCDXL/FreeXList                                          RunCDXL/FreeXList
  291.  
  292.    NAME
  293.     FreeXList -- Free list of struct CDXL or CDTV_CDXL.
  294.  
  295.    SYNOPSIS
  296.     FreeXList( xllist, CDXL_ob );
  297.  
  298.     VOID FreeXList( struct MinList *, CDXLOB * );
  299.  
  300.    FUNCTION
  301.     Free the transfer list. This list will contain either
  302.     struct CDXL or CDTV_CDXL depending upon which device 
  303.     was opened.
  304.  
  305.    INPUTS
  306.     xllist = pointer to a struct MinList.
  307.     CDLX_ob = pointer to defining CDXLOB control structure.
  308.  
  309.    RESULTS
  310.  
  311.  
  312.    NOTES
  313.  
  314.  
  315.    SEE ALSO
  316.     cdxlob.h
  317.  
  318.    BUGS
  319.     None?
  320.  
  321. RunCDXL/GetCDInfo                                          RunCDXL/GetCDInfo
  322.  
  323.    NAME
  324.     GetCDInfo -- Send a CD_INFO command to cd.device.
  325.  
  326.    SYNOPSIS
  327.     success = GetCDInfo( cdi );
  328.  
  329.     BOOL GetCDInfo( struct CDInfo * );
  330.  
  331.    FUNCTION
  332.     Send a CD_INFO command to cd.device. The info is stored in the 
  333.     cdinfo structure passed in.
  334.  
  335.    INPUTS
  336.     cdi = pointer to a struct CDInfo.
  337.  
  338.  
  339.    RESULTS
  340.     TRUE if successful, the struct CDInfo passed in will have its
  341.     fields set to reflect the info obtained from cd.device.
  342.  
  343.     FALSE if an error occured.
  344.  
  345.    NOTES
  346.  
  347.    SEE ALSO
  348.  
  349.    BUGS
  350.     None?
  351.  
  352. RunCDXL/NewCDTV_XL                                          RunCDXL/NewCDTV_XL
  353.  
  354.    NAME
  355.     NewCDTV_XL -- Allocate a CDTV_CDXL structure and AddTail it
  356.         to the transfer list.
  357.  
  358.    SYNOPSIS
  359.     error = NewCDTV_XL( first, buf, len, code );
  360.  
  361.     int NewCDTV_XL( struct MinList *, UBYTE *, ULONG, PF );
  362.  
  363.  
  364.    FUNCTION
  365.     Allocates a CDTV_CDXL structure and adds it to the transfer list.
  366.     Call this if cdtv.device was opened as opposed to NewCD_XL() for
  367.     cd.device.
  368.  
  369.    INPUTS
  370.     first = pointer to struct MinList.
  371.     buf = pointer to a transfer buffer.
  372.     len = ULONG length of buffer.
  373.     code = pointer to a function that will be called as an interrupt
  374.         whenever this transfer node has been completed.
  375.  
  376.    EXAMPLE
  377.     NewCDTV_XL( &XList, CDXL_ob->Buffer[i], CDXL_ob->FrameSize, CDXLCallBack );
  378.  
  379.  
  380.    RESULTS
  381.     0 if successful. An error code if not. Errors defined in
  382.     runcdxl.h
  383.  
  384.    NOTES
  385.  
  386.  
  387.    SEE ALSO
  388.     runcdxl.h cdxlob.h
  389.  
  390.    BUGS
  391.     None?
  392.  
  393. RunCDXL/NewCD_XL                                            RunCDXL/NewCD_XL
  394.  
  395.    NAME
  396.     NewCD_XL -- Allocate a CDXL structure and AddTail it
  397.         to the transfer list.
  398.  
  399.    SYNOPSIS
  400.     error = NewCD_XL( first, buf, len, code );
  401.  
  402.     int NewCD_XL( struct MinList *, UBYTE *, ULONG, PF );
  403.  
  404.  
  405.    FUNCTION
  406.     Allocates a CDXL structure and adds it to the transfer list.
  407.     Call this if cd.device was opened as opposed to NewCDTV_XL() for
  408.     cdtv.device.
  409.  
  410.    INPUTS
  411.     first = pointer to struct MinList.
  412.     buf = pointer to a transfer buffer.
  413.     len = ULONG length of buffer.
  414.     code = pointer to a function that will be called as an interrupt
  415.         whenever this transfer node has been completed.
  416.  
  417.    EXAMPLE
  418.     NewCD_XL( &XList, CDXL_ob->Buffer[i], CDXL_ob->FrameSize, CDXLCallBack );
  419.  
  420.  
  421.    RESULTS
  422.     0 if successful. An error code if not. Errors defined in
  423.     runcdxl.h
  424.  
  425.    NOTES
  426.  
  427.  
  428.    SEE ALSO
  429.     runcdxl.h cdxlob.h
  430.  
  431.    BUGS
  432.     None?
  433.  
  434. RunCDXL/Pan2Display                                      RunCDXL/Pan2Display
  435.  
  436.    NAME
  437.     Pan2Display -- Determine display from a Pan structure.
  438.  
  439.    SYNOPSIS
  440.     Pan2Display( pan, disp_def, flags );
  441.  
  442.     VOID Pan2Display( PAN *, DISP_DEF *, ULONG );
  443.  
  444.    FUNCTION
  445.     Given a Pan structure and a DISP_DEF structure, determine what 
  446.     kind of display to open and set fields in the DISP_DEF structure
  447.     to tell the display opening functions what kind of display to open.
  448.  
  449.    INPUTS
  450.     pan     = pointer to struct Pan read from CDXL file.
  451.     disp_def= pointer to DISP_DEF, display definition structure.
  452.     flags    = ULONG flags.
  453.  
  454.    RESULTS
  455.  
  456.  
  457.    NOTES
  458.  
  459.  
  460.    SEE ALSO
  461.     cdtv/pan.h runcdxl.h
  462.  
  463.    BUGS
  464.     None?
  465.  
  466.  
  467. RunCDXL/PlayCDXL                                            RunCDXL/PlayCDXL
  468.  
  469.    NAME
  470.     PlayCDXL -- Play a CDXL.
  471.  
  472.    SYNOPSIS
  473.     error = PlayCDXL( disp_def, CDXL_ob );
  474.  
  475.     int PlayCDXL( DISP_DEF *, CDXLOB * );
  476.  
  477.  
  478.    FUNCTION
  479.     Contains the main loop which handles the CDXL playback.
  480.     Waits and handles signals from:
  481.  
  482.         The CDXL interrupt,
  483.         The user telling us to abort,
  484.         The device telling us something is wrong,
  485.         The copper interrupt telling us to Call ChangeVPBitMap().
  486.  
  487.     Plays the CDXL until an abort signal is recieved or until the
  488.     last frame is reached.
  489.  
  490.  
  491.    INPUTS
  492.     disp_def = pointer to DISP_DEF, display definition structure.
  493.     CDXL_ob = pointer to defining CDXLOB control structure.
  494.  
  495.  
  496.    RESULTS
  497.     0 if successful. An error code if not. Errors defined in
  498.     runcdxl.h
  499.  
  500.  
  501.    NOTES
  502.  
  503.  
  504.    SEE ALSO
  505.     runcdxl.h cdxlob.h
  506.  
  507.    BUGS
  508.     None?
  509.  
  510.  
  511. RunCDXL/RunCDXL                                         RunCDXL/RunCDXL
  512.  
  513.    NAME
  514.     RunCDXL -- Main CDXL entry point.
  515.  
  516.    SYNOPSIS
  517.     error = RunCDXL( tag, ... );
  518.  
  519.     int RunCDXL( ULONG, ... )
  520.  
  521.  
  522.    FUNCTION
  523.     CDXL entry point. Takes a taglist which defines the options.
  524.  
  525.  
  526.    INPUTS
  527.     tag -
  528.     XLTAG_XLFile:    ti_Data points to CDXL filename.
  529.  
  530.     XLTAG_View:        ti_Data is a boolean value which if TRUE instructs the 
  531.             display opening routines to open a view as opposed to 
  532.             a screen. Default is FALSE (open a screen).
  533.  
  534.     XLTAG_Blit:        ti_Data is a boolean value which if TRUE forces the 
  535.             CDXL image to be loaded into a buffer which is then 
  536.             blitted to the display. This is in contrast to the 
  537.             default mode where the CDXL image is loaded directly 
  538.             to the display memory.
  539.  
  540.     XLTAG_Background:    ti_Data points to an ILBM filename to display 
  541.             in the background. If specified, XLTAG_Blit is
  542.             implied.
  543.  
  544.     XLTAG_Left:        ti_Data specifies left edge of CDXL image. Default
  545.             is to center.
  546.  
  547.     XLTAG_Top:        ti_Data specifies top edge of CDXL image. Default
  548.             is to center.
  549.  
  550.     XLTAG_Volume:    ti_Data specifies volume for CDXL audio. Default
  551.             is 64.
  552.  
  553.     XLTAG_MultiPalette:    ti_Data is a boolean value which if TRUE forces
  554.             a palette load for each CDXL frame. Default is FALSE.
  555.  
  556.     XLTAG_KillSig:    ti_Data is a ULONG signal which will abort the CDXL 
  557.             playback.
  558.  
  559.     XLTAG_XLSpeed:    ti_Data is a READXLSPEED override value. Default is
  560.             what is stored in the Pan->Reserved + 1 * 75. 
  561.  
  562.     XLTAG_XLEEC:    ti_Data is a boolean value that if TRUE turns on
  563.             error correction. Default is FALSE.
  564.  
  565.     XLTAG_XLPalette:    ti_Data is a boolean value that if TRUE forces the
  566.             display to use the palette stored in the CDXL. Useful 
  567.             in conjuction with XLTAG_Background, to override
  568.             the background ILBM's palette.
  569.  
  570.     XLTAG_LACE:        ti_Data is a boolean value that if TRUE forces the
  571.             display to open in interlace mode, overriding ILBM
  572.             or CDXL setting.
  573.  
  574.     XLTAG_NONLACE:    ti_Data is a boolean value that if TRUE forces the
  575.             display to open in NON interlace mode, overriding ILBM
  576.             or CDXL setting.
  577.  
  578.     XLTAG_HIRES:    ti_Data is a boolean value that if TRUE forces the
  579.             display to open in Hires mode, overriding ILBM
  580.             or CDXL setting.
  581.  
  582.     XLTAG_LORES:    ti_Data is a boolean value that if TRUE forces the
  583.             display to open in LORES mode, overriding ILBM
  584.             or CDXL setting.
  585.  
  586.     XLTAG_BOXIT:    ti_Data is a boolean value that if TRUE forces a
  587.             box to be drawn in color 0 around the CDXL image.
  588.             May be needed to avoid some HAMing problems.
  589.  
  590.  
  591.    RESULTS
  592.     0 if successful. An error code if not. Errors defined in
  593.     runcdxl.h
  594.  
  595.  
  596.    NOTES
  597.  
  598.  
  599.    SEE ALSO
  600.     runcdxl.h cdxlob.h
  601.  
  602.    BUGS
  603.     None?
  604.  
  605.  
  606. RunCDXL/SendIOR                                           RunCDXL/SendIOR
  607.  
  608.    NAME
  609.     SendIOR -- asynchronously execute a device command.
  610.  
  611.    SYNOPSIS
  612.     success = SendIOR( req, cmd, off, len, data );
  613.  
  614.     BOOL SendIOR( struct IOStdReq *, LONG, LONG, LONG, APTR );
  615.  
  616.    FUNCTION
  617.     asynchronously execute a device command.
  618.  
  619.    INPUTS
  620.     req = pointer to properly initialized IOStdReq structure.
  621.     cmd = device command for io_Command.
  622.     off = offset for io_Offset.
  623.     len = length for io_Length.
  624.     data = data for io_Data.
  625.  
  626.    RESULTS
  627.     TRUE if successful.
  628.     FALSE if an error occurs. Error can be found in req->io_Error.
  629.  
  630.    NOTES
  631.  
  632.  
  633.    SEE ALSO
  634.  
  635.    BUGS
  636.     None?
  637.  
  638.  
  639. RunCDXL/StartCDXL                                       RunCDXL/StartCDXL
  640.  
  641.    NAME
  642.     StartCDXL -- Prepare to play the CDXL.
  643.  
  644.    SYNOPSIS
  645.     error = StartCDXL( DISP_DEF *, CDXLOB * );
  646.  
  647.     int StartCDXL( DISP_DEF *, CDXLOB * );
  648.  
  649.    FUNCTION
  650.     Preps transfer lists etc. then calls PlayCDXL().
  651.  
  652.  
  653.    INPUTS
  654.     disp_def = pointer to DISP_DEF, display definition structure.
  655.     CDXL_ob = pointer to defining CDXLOB control structure.
  656.  
  657.  
  658.    RESULTS
  659.     0 if successful. An error code if not. Errors defined in
  660.     runcdxl.h
  661.  
  662.  
  663.    NOTES
  664.  
  665.  
  666.    SEE ALSO
  667.     runcdxl.h cdxlob.h
  668.  
  669.    BUGS
  670.     None?
  671.  
  672.